█

minecraft text-filtering

Overview of the hidden Minecraft server feature that allows filtering player messages.

release date: 2025-08-31

modification date: 2025-08-31

my API

preliminary topics

Almost everyone probably knows the game Minecraft. A success of Mojang, seemingly untouchable by any serious hate, and anyone who has tried it loves this game. Right?

Some time ago, I started exploring the possibilities of a Minecraft server. I experimented with configurations, datapacks, options for tunneling the game to public networks, etc. I even created a working and highly configurable Minecraft Server launcher on Termux - >here<.

What caught my attention the most, however, was the empty option text-filtering-config= in the server.properties file. What is this option for? The name says it all. Unfortunately, there is no official information anywhere on how to use it...

what does this thing do?

The name of the configuration option (text-filtering-config) clearly indicates that it is meant for text filtering. That’s fairly obvious. The only text that can be filtered in real-time is chat messages. So, does this script allow filtering/censoring those messages? Sounds like a breakthrough!

Many servers struggle with issues like profanity, spam, and advertising — a native, built-in option in Vanilla Minecraft could finally solve this once and for all. The problem, however, is that nobody knows what exactly to put there...

Time to roll up my sleeves, sit at the computer, and start searching...

a bit more research

Finding documentation for this feature was impossible. Literally, zero official docs. The only useful material online was a similar article by the developer Walshy, describing how this option worked in Minecraft 1.16.4. This gave me some insight.

However, his article had some inconsistencies, and his code didn’t work on versions 1.19+, which confirmed that Mojang has been working on this feature and its mechanics have changed.

Link to Walshy’s article - >here<.

I decided I couldn’t give up, so my next step was to try putting something there myself - foolish? Yet doing so triggered an error in the server logs, revealing the exact name of the Java class that caused it. Knowing which classes handle this feature, I decided to try decompiling them and see in the code what does what and why.

Browsing the decompiled code wasn’t easy (anyone who’s tried those online Java decompilers knows why), but I roughly understood what Minecraft sends to the API server and what kind of response it expects back. Now all that was left was to start writing the backend and experimenting.

experiments

After the initial experiments, reviewing the HTTP server logs, and some testing, I learned that Minecraft connects to specific URLs at a given address, sends specific data along with an authorization header, and expects a JSON response with instructions on what to do. An example JSON is shown below: 

{
    "response": boolean,
    "hashed": "string",
    "hashes": ["el1", "el2"]
}
or: 

{
    "response": boolean
}
Minecraft expects a single key response without hashes or hashed when the message is fully acceptable to send - no censorship is needed.

result and summary

I managed to get it running. Although not everything is fully understood yet, it’s now clear that player messages can be censored on a Vanilla Minecraft Server. A breakthrough?

The real puzzle remains the behavior of the hashed key (which in my API currently serves just as information, since Minecraft doesn’t actually respect it) and the fact that Minecraft also connects to the API server on join and leave events for each player.

Despite that - we got it! A working native message filter in Minecraft! The appropriate backend can detect and filter any type of message or text. Mine focused on profanity and URLs (to block ads).

To finish, here’s a short video from the game itself, showing my filter in action:
Are you running a Vanilla Minecraft Server and want to try my API on your own server? Check >here< for more information about the ready-to-use project.